home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / AppleGuide.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  9.6 KB  |  383 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        AppleGuide.h
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    ©1994-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __APPLEGUIDE__
  19. #define __APPLEGUIDE__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __APPLEEVENTS__
  25. #include <AppleEvents.h>
  26. #endif
  27. #ifndef __FILES__
  28. #include <Files.h>
  29. #endif
  30.  
  31.  
  32.  
  33.  
  34. #if PRAGMA_ONCE
  35. #pragma once
  36. #endif
  37.  
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41.  
  42. #if PRAGMA_IMPORT
  43. #pragma import on
  44. #endif
  45.  
  46. #if PRAGMA_STRUCT_ALIGN
  47.     #pragma options align=mac68k
  48. #elif PRAGMA_STRUCT_PACKPUSH
  49.     #pragma pack(push, 2)
  50. #elif PRAGMA_STRUCT_PACK
  51.     #pragma pack(2)
  52. #endif
  53.  
  54. /* Types*/
  55. typedef UInt32                             AGRefNum;
  56. typedef UInt32                             AGCoachRefNum;
  57. typedef UInt32                             AGContextRefNum;
  58. struct AGAppInfo {
  59.     AEEventID                         eventId;
  60.     long                             refCon;
  61.     void *                            contextObj;                    /* private system field*/
  62. };
  63. typedef struct AGAppInfo AGAppInfo;
  64.  
  65. typedef AGAppInfo *                        AGAppInfoPtr;
  66. typedef AGAppInfoPtr *                    AGAppInfoHdl;
  67. typedef CALLBACK_API( OSErr , CoachReplyProcPtr )(Rect *pRect, Ptr name, long refCon);
  68. typedef CALLBACK_API( OSErr , ContextReplyProcPtr )(Ptr pInputData, Size inputDataSize, Ptr *ppOutputData, Size *pOutputDataSize, AGAppInfoHdl hAppInfo);
  69. typedef STACK_UPP_TYPE(CoachReplyProcPtr)                         CoachReplyUPP;
  70. typedef STACK_UPP_TYPE(ContextReplyProcPtr)                     ContextReplyUPP;
  71. enum { uppCoachReplyProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  72. enum { uppContextReplyProcInfo = 0x0000FFE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  73. #define NewCoachReplyProc(userRoutine)                             (CoachReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppCoachReplyProcInfo, GetCurrentArchitecture())
  74. #define NewContextReplyProc(userRoutine)                         (ContextReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppContextReplyProcInfo, GetCurrentArchitecture())
  75. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)     CALL_THREE_PARAMETER_UPP((userRoutine), uppCoachReplyProcInfo, (pRect), (name), (refCon))
  76. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo)  CALL_FIVE_PARAMETER_UPP((userRoutine), uppContextReplyProcInfo, (pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  77. /* Constants*/
  78.  
  79.  
  80.  
  81. enum {
  82.     kAGDefault                    = 0,
  83.     kAGFrontDatabase            = 1,
  84.     kAGNoMixin                    = (-1)
  85. };
  86.  
  87.  
  88.  
  89. enum {
  90.     kAGViewFullHowdy            = 1,                            /* Full-size Howdy*/
  91.     kAGViewTopicAreas            = 2,                            /* Full-size Topic Areas*/
  92.     kAGViewIndex                = 3,                            /* Full-size Index Terms*/
  93.     kAGViewLookFor                = 4,                            /* Full-size Look-For (Search)*/
  94.     kAGViewSingleHowdy            = 5,                            /* Single-list-size Howdy*/
  95.     kAGViewSingleTopics            = 6                                /* Single-list-size Topics*/
  96. };
  97.  
  98.  
  99.  
  100. enum {
  101.     kAGFileMain                    = FOUR_CHAR_CODE('poco'),
  102.     kAGFileMixin                = FOUR_CHAR_CODE('mixn')
  103. };
  104.  
  105. /* To test against AGGetAvailableDBTypes*/
  106.  
  107. enum {
  108.     kAGDBTypeBitAny                = 0x00000001,
  109.     kAGDBTypeBitHelp            = 0x00000002,
  110.     kAGDBTypeBitTutorial        = 0x00000004,
  111.     kAGDBTypeBitShortcuts        = 0x00000008,
  112.     kAGDBTypeBitAbout            = 0x00000010,
  113.     kAGDBTypeBitOther            = 0x00000080
  114. };
  115.  
  116.  
  117. typedef UInt16                             AGStatus;
  118. /* Returned by AGGetStatus*/
  119.  
  120. enum {
  121.     kAGIsNotRunning                = 0,
  122.     kAGIsSleeping                = 1,
  123.     kAGIsActive                    = 2
  124. };
  125.  
  126.  
  127. typedef UInt16                             AGWindowKind;
  128. /* Returned by AGGetFrontWindowKind*/
  129.  
  130. enum {
  131.     kAGNoWindow                    = 0,
  132.     kAGAccessWindow                = 1,
  133.     kAGPresentationWindow        = 2
  134. };
  135.  
  136. /* Error Codes*/
  137.  
  138. /* Not an enum, because other OSErrs are valid.*/
  139. typedef SInt16                             AGErr;
  140. /* Apple Guide error codes*/
  141.  
  142. enum {
  143.                                                                 /* -------------------- Apple event reply codes*/
  144.     kAGErrUnknownEvent            = -2900,
  145.     kAGErrCantStartup            = -2901,
  146.     kAGErrNoAccWin                = -2902,
  147.     kAGErrNoPreWin                = -2903,
  148.     kAGErrNoSequence            = -2904,
  149.     kAGErrNotOopsSequence        = -2905,
  150.     kAGErrReserved06            = -2906,
  151.     kAGErrNoPanel                = -2907,
  152.     kAGErrContentNotFound        = -2908,
  153.     kAGErrMissingString            = -2909,
  154.     kAGErrInfoNotAvail            = -2910,
  155.     kAGErrEventNotAvailable        = -2911,
  156.     kAGErrCannotMakeCoach        = -2912,
  157.     kAGErrSessionIDsNotMatch    = -2913,
  158.     kAGErrMissingDatabaseSpec    = -2914,                        /* -------------------- Coach's Chalkboard reply codes*/
  159.     kAGErrItemNotFound            = -2925,
  160.     kAGErrBalloonResourceNotFound = -2926,
  161.     kAGErrChalkResourceNotFound    = -2927,
  162.     kAGErrChdvResourceNotFound    = -2928,
  163.     kAGErrAlreadyShowing        = -2929,
  164.     kAGErrBalloonResourceSkip    = -2930,
  165.     kAGErrItemNotVisible        = -2931,
  166.     kAGErrReserved32            = -2932,
  167.     kAGErrNotFrontProcess        = -2933,
  168.     kAGErrMacroResourceNotFound    = -2934,                        /* -------------------- API reply codes*/
  169.     kAGErrAppleGuideNotAvailable = -2951,
  170.     kAGErrCannotInitCoach        = -2952,
  171.     kAGErrCannotInitContext        = -2953,
  172.     kAGErrCannotOpenAliasFile    = -2954,
  173.     kAGErrNoAliasResource        = -2955,
  174.     kAGErrDatabaseNotAvailable    = -2956,
  175.     kAGErrDatabaseNotOpen        = -2957,
  176.     kAGErrMissingAppInfoHdl        = -2958,
  177.     kAGErrMissingContextObject    = -2959,
  178.     kAGErrInvalidRefNum            = -2960,
  179.     kAGErrDatabaseOpen            = -2961,
  180.     kAGErrInsufficientMemory    = -2962
  181. };
  182.  
  183. /* Events*/
  184.  
  185. /* Not an enum because we want to make assignments.*/
  186. typedef UInt32                             AGEvent;
  187. /* Handy events for AGGeneral.*/
  188.  
  189. enum {
  190.                                                                 /* Panel actions (Require a presentation window).*/
  191.     kAGEventDoCoach                = FOUR_CHAR_CODE('doco'),
  192.     kAGEventDoHuh                = FOUR_CHAR_CODE('dhuh'),
  193.     kAGEventGoNext                = FOUR_CHAR_CODE('gonp'),
  194.     kAGEventGoPrev                = FOUR_CHAR_CODE('gopp'),
  195.     kAGEventHidePanel            = FOUR_CHAR_CODE('pahi'),
  196.     kAGEventReturnBack            = FOUR_CHAR_CODE('gobk'),
  197.     kAGEventShowPanel            = FOUR_CHAR_CODE('pash'),
  198.     kAGEventTogglePanel            = FOUR_CHAR_CODE('patg')
  199. };
  200.  
  201. /* Functions*/
  202.  
  203. /*
  204.    AGClose
  205.    Close the database associated with the AGRefNum.
  206. */
  207.  
  208. EXTERN_API( AGErr )
  209. AGClose                            (AGRefNum *                refNum)                                TWOWORDINLINE(0x7011, 0xAA6E);
  210.  
  211. /*
  212.    AGGeneral
  213.    Cause various events to happen.
  214. */
  215.  
  216. EXTERN_API( AGErr )
  217. AGGeneral                        (AGRefNum                 refNum,
  218.                                  AGEvent                 theEvent)                            TWOWORDINLINE(0x700D, 0xAA6E);
  219.  
  220. /*
  221.    AGGetAvailableDBTypes
  222.    Return the database types available for this application.
  223. */
  224.  
  225. EXTERN_API( UInt32 )
  226. AGGetAvailableDBTypes            (void)                                                        TWOWORDINLINE(0x7008, 0xAA6E);
  227.  
  228. /*
  229.    AGGetFrontWindowKind
  230.    Return the kind of the front window.
  231. */
  232.  
  233. EXTERN_API( AGWindowKind )
  234. AGGetFrontWindowKind            (AGRefNum                 refNum)                                TWOWORDINLINE(0x700C, 0xAA6E);
  235.  
  236. /*
  237.    AGGetFSSpec
  238.    Return the FSSpec for the AGRefNum.
  239. */
  240.  
  241. EXTERN_API( AGErr )
  242. AGGetFSSpec                        (AGRefNum                 refNum,
  243.                                  FSSpec *                fileSpec)                            TWOWORDINLINE(0x700F, 0xAA6E);
  244.  
  245. /*
  246.    AGGetStatus
  247.    Return the status of Apple Guide.
  248. */
  249.  
  250. EXTERN_API( AGStatus )
  251. AGGetStatus                        (void)                                                        TWOWORDINLINE(0x7009, 0xAA6E);
  252.  
  253. /*
  254.    AGInstallCoachHandler
  255.    Install a Coach object location query handler.
  256. */
  257.  
  258. EXTERN_API( AGErr )
  259. AGInstallCoachHandler            (CoachReplyUPP             coachReplyProc,
  260.                                  long                     refCon,
  261.                                  AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7012, 0xAA6E);
  262.  
  263. /*
  264.    AGInstallContextHandler
  265.    Install a context check query handler.
  266. */
  267.  
  268. EXTERN_API( AGErr )
  269. AGInstallContextHandler            (ContextReplyUPP         contextReplyProc,
  270.                                  AEEventID                 eventID,
  271.                                  long                     refCon,
  272.                                  AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7013, 0xAA6E);
  273.  
  274. /*
  275.    AGIsDatabaseOpen
  276.    Return true if the database associated with the AGRefNum is open.
  277. */
  278.  
  279. EXTERN_API( Boolean )
  280. AGIsDatabaseOpen                (AGRefNum                 refNum)                                TWOWORDINLINE(0x7006, 0xAA6E);
  281.  
  282. /*
  283.    AGOpen
  284.    Open a guide database.
  285. */
  286.  
  287. EXTERN_API( AGErr )
  288. AGOpen                            (ConstFSSpecPtr         fileSpec,
  289.                                  UInt32                 flags,
  290.                                  Handle                 mixinControl,
  291.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7001, 0xAA6E);
  292.  
  293. /*
  294.    AGOpenWithSearch
  295.    Open a guide database and preset a search string.
  296. */
  297.  
  298. EXTERN_API( AGErr )
  299. AGOpenWithSearch                (ConstFSSpecPtr         fileSpec,
  300.                                  UInt32                 flags,
  301.                                  Handle                 mixinControl,
  302.                                  ConstStr255Param         searchString,
  303.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7002, 0xAA6E);
  304.  
  305. /*
  306.    AGOpenWithSequence
  307.    Open a guide database and display a presentation window sequence.
  308. */
  309.  
  310. EXTERN_API( AGErr )
  311. AGOpenWithSequence                (ConstFSSpecPtr         fileSpec,
  312.                                  UInt32                 flags,
  313.                                  Handle                 mixinControl,
  314.                                  short                     sequenceID,
  315.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7004, 0xAA6E);
  316.  
  317. /*
  318.    AGOpenWithView
  319.    Open a guide database and override the default view.
  320. */
  321.  
  322. EXTERN_API( AGErr )
  323. AGOpenWithView                    (ConstFSSpecPtr         fileSpec,
  324.                                  UInt32                 flags,
  325.                                  Handle                 mixinControl,
  326.                                  short                     viewNum,
  327.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7005, 0xAA6E);
  328.  
  329. /*
  330.    AGQuit
  331.    Make Apple Guide quit.
  332. */
  333.  
  334. EXTERN_API( AGErr )
  335. AGQuit                            (void)                                                        TWOWORDINLINE(0x7010, 0xAA6E);
  336.  
  337. /*
  338.    AGRemoveCoachHandler
  339.    Remove the Coach object location query handler.
  340. */
  341.  
  342. EXTERN_API( AGErr )
  343. AGRemoveCoachHandler            (AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7014, 0xAA6E);
  344.  
  345. /*
  346.    AGRemoveContextHandler
  347.    Remove the context check query handler.
  348. */
  349.  
  350. EXTERN_API( AGErr )
  351. AGRemoveContextHandler            (AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7015, 0xAA6E);
  352.  
  353. /*
  354.    AGStart
  355.    Start up Apple Guide in the background.
  356. */
  357.  
  358. EXTERN_API( AGErr )
  359. AGStart                            (void)                                                        TWOWORDINLINE(0x700A, 0xAA6E);
  360.  
  361.  
  362.  
  363. #if PRAGMA_STRUCT_ALIGN
  364.     #pragma options align=reset
  365. #elif PRAGMA_STRUCT_PACKPUSH
  366.     #pragma pack(pop)
  367. #elif PRAGMA_STRUCT_PACK
  368.     #pragma pack()
  369. #endif
  370.  
  371. #ifdef PRAGMA_IMPORT_OFF
  372. #pragma import off
  373. #elif PRAGMA_IMPORT
  374. #pragma import reset
  375. #endif
  376.  
  377. #ifdef __cplusplus
  378. }
  379. #endif
  380.  
  381. #endif /* __APPLEGUIDE__ */
  382.  
  383.